<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Working with Join Fields : DataMapper ORM - User Guide</title>

<link rel="shortcut icon" type="image/png" href="../images/favicon.png" />
<link rel="stylesheet" type="text/css" media="all" href="../css/userguide.css" />
<link rel="alternate" type="application/rss+xml" title="Datamapper ORM Updates Feed" href="/rss.xml" />

<meta http-equiv="expires" content="-1" />
<meta http-equiv= 'pragma' content="no-cache" />
<meta name="robots" content="all" />

</head>

<body>

<!-- START NAVIGATION -->
<div id="nav"><div id="nav_inner"></div></div>
<div id="nav2"><a name="top">&nbsp;</a><a id="nav_toggle" href="#"><img src="../images/nav_toggle_darker.jpg" width="154" height="43" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
<div id="masthead">
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td><h1>DataMapper ORM</h1></td>
<td id="breadcrumb_right"><a href="toc.html">Table of Contents Page</a></td>
</tr>
</table>
</div>
<!-- END NAVIGATION -->

<!-- START BREADCRUMB -->
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td id="breadcrumb">
<a href="/">Datamapper ORM Home</a> &nbsp;&#8250;&nbsp;
<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
Working with Join Fields
</td>
</tr>

</table>
<!-- END BREADCRUMB -->

<br clear="all" />


<!-- START CONTENT -->
<div id="content">


<h1>Working with Join Fields</h1>

<p>Join fields are fields that are stored on the join table for Many to Many relationships.  They can be used to store additional information that is only relevant to the relationship itself, as opposed to information that belongs to one of the models.</p>

<p>A good example of this is a system that can fire alarms.  Each alarm can be assigned to multiple users, and each user can have multiple alarms.  An alarm needs to be fired individually for each user, and they only get fired when the user logs in.</p>

<p>To keep track of this, we add a column to our <strong>alarms_users</strong> table that is called <var><i>wasfired</i></var>.  It defaults to FALSE.</p>
<h3>alarms_users</h3>
<table cellpadding="0" cellspacing="1" border="0" class="tableborder">
<tr>
	<th>id</th>
	<th>alarm_id</th>
	<th>user_id</th>
	<th>wasfired</th>
</tr>
<tr>
	<td>1</td>
	<td>1</td>
	<td>4</td>
	<td>FALSE</td>
</tr>
<tr>
	<td>2</td>
	<td>1</td>
	<td>5</td>
	<td>TRUE</td>
</tr>
<tr>
	<td>3</td>
	<td>2</td>
	<td>1</td>
	<td>TRUE</td>
</tr>
</table>

<h2>Querying the Join Field</h2>
<p>Please see <a href="getadvanced.html#_join_field">Get (Advanced): _join_field</a> for details on how to query join fields.</p>

<h2>Reading the Join Field</h2>
<p>Please see <a href="getadvanced.html#include_join_fields">Get (Advanced): include_join_fields</a> for details on how to include join fields in the result set.</p>

<h2 id="set_join_field">Setting the Join Field</h2>
<p>You can set the join field for one or more rows using <strong>set_join_field</strong></p>
<h3>$object->set_join_field($model, $column, $value)</h3>
<p>Store <var><i>$value</i></var> into <dfn>$column</dfn> on the table that relates $object and <var><s>$model</s></var> (which can be an object OR a field name when an object is related multiple times.</p>
<ul>
	<li><var><s>$model</s></var>: One of the following
		<ul>
			<li>A specific object (most common)</li>
			<li>A one-item associative array in the form of <strong>array('relationship_key' => $related_object)</strong></li>
			<li>A model name*</li>
			<li>A relationship key*</li>
		</ul>
		<p class="note">* In the case of the latter two, <em>every row</em> that is related to $object will be updated.</p></li>
	<li><dfn>$column</dfn>: The column to set</li>
	<li><var><i>$value</i></var>: The value to set on the column</li>
</ul>

<p>Example time!</p>
<pre>
<samp>// Create objects
</samp><var>$u </var><kbd>= new </kbd><var>User</var><kbd>();
</kbd><var>$u</var><kbd>-&gt;</kbd><var><u>get_by_id</u></var><kbd>(</kbd><var>$userid</var><kbd>);

</kbd><var>$alarm </var><kbd>= new </kbd><var>Alarm</var><kbd>();
</kbd><var>$alarm</var><kbd>-&gt;</kbd><var><u>get_by_id</u></var><kbd>(</kbd><var>$alarmid</var><kbd>);

</kbd><samp>// mark this alarm as fired
</samp><var>$alarm</var><kbd>-&gt;</kbd><var><u>set_join_field</u></var><kbd>(</kbd><var><s>$u</s></var><kbd>, </kbd><dfn>'wasfired'</dfn><kbd>, </kbd><var><i>TRUE</i></var><kbd>);</kbd>
</pre>

</div>
<!-- END CONTENT -->


<div id="footer">
<p>
<span id="footer_previous">Previous Topic:&nbsp;&nbsp;<a href=""></a>
&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;</span>
<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
<a href="../index.html">User Guide Home</a>
<span id="footer_next">&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
Next Topic:&nbsp;&nbsp;<a href=""></a></span>
</p>
<div id="copyrights">
<p><a href="/">Datamapper ORM</a> &nbsp;&middot;&nbsp; Copyright &copy; 2010-2011 &nbsp;&middot;&nbsp; Harro "WanWizard" Verton</p>
<p><a href="license.html">Other License Information</a></p>
</div>
</div>

<script type="text/javascript" src="../js/mootools.js"></script>
<script type="text/javascript" src="../js/menu.js"></script>
<script type="text/javascript">
<!--
	window.addEvent('domready', function() {

		// Create Menu
		var menu = new Menu({
			basepath: '../',
			pagespath: ''
		});

	});
//-->
</script>
</body>
</html>
